Roller

	This plug-in is written in Python 2.7 for GIMP v2.10.38. Roller is designed to create image compositions like wallpaper, image boards, collages, etc. Roller 1 through 6 presets are incompatible with Roller 7.

	Please note that Roller requires access to the hard drive, its installation folder to be exact, in order to save preset data. If Roller can't save a preset, then the plugin will shutdown, and spit out an error.

Basics

	Steps

	Roller breaks a render into steps. Steps are how an option group produces layer output. Global, Light, Backdground are examples of an option group, each having a step. Some steps have a sub-step. A sub-step will produce an additional layer in a step's group layer.

    A View Button
    
    A view button when activated causes steps to be processed. There are two basic view types: Plan and a work-in-progress (work). For each basic view, there are two process options, a partial and a complete view. For planning, draft produces a partial plan. A partial view ends its output on the focused option-group-step in the main window. When working, the Peek option is the partial option, while an activated Preview makes a complete view.

	Composition

	Roller creates layers like a pancake robot in a sci-fi movie, but the Background layer and the Light output deserve a mention.

	Every composition has a Background layer. This layer serves as a backdrop for the composition and may provide visible material for Accent output. Some Accent depend on the pixels in the background. The Accent list has a tool-tip that indicates this dependency.

	Light is a material layer that is used in multiple parts of a render. It's purpose is to simulate a light source or an environment, but it has other uses, such as unifying a composition. Heat materials indicate where Light layers are placed.

Model

	Each model offers unique possibilities for composing. Roller has several models: Table, Cell, Stack, Box, Pyramid, and Sidewalk. Models share some common characteristics. They all have a Property and a Cell/Type option group.

    After creating a model, steps need to be added to the navigation tree in order to produce layer output. Select the Model/Revise button to determine which steps the selected active model will contain. Select the Model/Step button to move steps from a storage shelf to active status.

	Table
	
	The Table model has two branches: Canvas and Cell. The Canvas branch has options for modifying the canvas rectangle. The Cell branch is very much like the Canvas branch, except for the options apply to a user-defined cell rectangle.

	Grid-type models divide the canvas into a grid defined by row and column counts. Row and column intersections form a cell. The main window options apply to the entire grid. If a single cell needs to modified, the Per option is used. Table, Box, and Sidewalk are grid-type models.

	The Per option when selected provides access to a grid layout which in turn opens a Cell Editor. The Cell/Type/Per option however only has a merge cell layout.

	Cell
	
	The Cell model has one branch: Cell. A Rectangle option defines a single cell rectangle for its output. A non-rectangular cell-shape is created with a mask placed over the cell rectangle.

	Stack
	
	A Stack model has one branch, and like Cell, uses a Rectangle option to define its first cell. When Stack has more than one cell, the Add Offset X and Add Offset Y options modify the additional cell rectangle positions. For each cell after the first, the offsets are added to the previous cell rectangle's position to determine the next cell's topleft position.

	Box
	
	The Box model has three branches: Canvas, Cell, and Face. The Box grid is the same grid as the Table's hexagon-shaped cell. It's a double-spaced grid where every other cell is valid. A Face option group applies itself to the three faces on the Box. The Per option's cell editor adapts to a Box/Face allowing for individual Face edition.

	Pyramid

	A Pyramid model has two branches, Canvas and Cell. Cell size is calculated evenly where each cell is gets an equal share in its scope. The wide end of the Pyramid is row one's location. If the Pyramid is facing up, then row one is at the bottom. If the Pyramid is facing down, row one is at the top of the Pyramid.

	Sidewalk

	A Sidewalk model has three branches, Canvas, Cell, and Facing. Cells are arranged in a rectangular ring. The Facing output is placed either inward or outward from the center of the cell ring. Cells on a side have perpendicular placed output, while the corner cells output direction is determined by the shape of the cell ring.

Step

	Steps are option groups visible in the user interface. The steps are processed from the top-down and left-to-right as reflected in the navigation tree. Output processing starts at the bottom of the Layers dock and ends at the top which is the reverse order of the navigation tree.

	Steps have two different states: active and shelved. Model step is managed from the Model/Revise dialog. The Revise dialog removes a step permanently. Active steps are visible in the user interface. A step can be shelved using the Step dialog. A shelved step retains its option values between Roller sessions.

Insight

	Steps Preset
	
	This option group is found on the trunk of the navigation tree at the bottom of the branch list. Its value is all of the step in the current Roller session. 

	The Last Used Steps Preset

	Roller writes a Last Used Steps Preset file after completing an Accept command from the main window. When the Roller starts it seeks and loads this Last Used Steps Preset. The user can manually choose write over the Last Used Steps Preset, if they wish to continue a session from a given point. 

	Cell Rectangle

	Every cell has a rectangle that defines a cell boundary. A cell's shape its determined by this limitation. However, there are other rectangles that effect how the final cell output, such as, the Shift and Margin options.

	Shift

	The Shift options adjust a rectangle's size and position. There are Canvas and Cell versions of Shift. The Cell version may have a Per option which can change a single cell's rectangle.
	
	Margin

	Margin options apply inside a rectangle. They produce a pocket rectangle. The Obey Margins option causes output to use the pocket limitation.

	Cell Shape
		
	A cell shape has two variations. The cell rectangle defines the original shape of the cell. If margins apply, then there is an additional cell shape created. Option groups will use one or the other cell shape when masking and sizing layer output.

	Image Mold

	The image mold is a process that ensures that an image fits inside its designated rectangle. If an image is larger than its rectangle, the image may be scaled down depending on the Image/Resize method. On the other hand, depending on the Resize method and image justification, an image may also be enlarged.

	Roller can use open images in GIMP when Roller starts, but only for making copies. Roller will make selections with open image files, but restores the original selection when closing. Roller never does anything else with either open or file image. The only image in which Roller manipulates on a pixel level is its rendered image.

	View Button

	The view buttons are on the bottom of a Roller window. Activating a view button will cause Roller to produce layer output.

	Background

	There are two options that take a snapshot of their background layers: Mean Color and Below. Both options make a snapshot by hiding the layers above and their own group-layer. Whenever the background changes, these two options update their content.

	Main and Per Output

	Main output is produced by an option based in the main window. If main output is multi-cell, the cell production is combined into one layer.

	Per output is produced by customizing an individual cell/face/facing. A Per output is separate from the main output, and placed on top of the main output.

Adding Frame Images to the Frame Folder
		
	During start-up, Roller compiles a list of '.png' file types from Roller's Frame folder. You can add additional frames to this folder. In order to add your own frames, they must be the '.png' file type. The frames are used solely by the Frame/Over option. My gratitude goes to dinasset from 'gimpchat.com' for sharing the provided frame files.

Errors And Limitations

	* If an image is referenced from a File or Folder image source is displaying black instead of image material, try converting the image to GIMP's sRGB color profile prior to running Roller.

	* Opening and closing images in GIMP while Roller is open may make Roller unstable.

	* Putting too many rows and columns into a composition grid may result in a crash. GTK has its limitations, and Roller doesn't compensate for scaling purposes. The Merge Cells window may come to a crawl when drawing a multitude of cells. I was able to create a grid of 15 rows and 15 columns without too much of a delay. So patience may be in order if you wish to create a larger grid of cells.

	* I recommend having the Layers Dock visible while running Roller as this dock will show GIMP working.

	* Roller doesn't save images. Roller does save Preset files inside the Roller/Resource/Preset folder.

	* Running two Roller scripts simultaneously is not supported.

	* When the script is run for the first time, Python creates ".pyc" type files within the Roller/Resource/Module folder. These files help the code run faster in the Python interpreter. The files are re-created if they go missing, so have no worries about deleting them.

	* Some dynamic brushes, when applied as brush stroke, with Roller brush output may not work.

	* Roller uses the clipboard to make image snapshots. If there is another background process also using the clipboard, then this can cause the copy and paste operation to fail resulting in a completely black copy and/or a possible Roller crash.

	* Testing and designing a composition can be sped up in several ways.
		1) Reduce the size of the render during testing.
		2) Shelve steps.
		3) Be mindful of the background update layers: Mean Color and Below which update when their backgrounds change.
		4) Try designing and processing steps in the order of their execution.

	* It's safe to adjust layer opacity and mode in the Layers Dock while Roller is idle. However, Roller typically won't see these kind of changes during its processing.

	* The Accent/Triangle Reverb may produce an irregular result if the Global/Work-in-Progress scale is too small. 

	* At times, you may notice seams between cells or other non-rectangular shapes. This anti-aliasing issue can be fixed by duplicating the layer in the final output. This works as long as the layer's has a Normal mode and 100% Opacity.

Special Thanks

	Many thanks to the free programs Notepad++ (for easy editing), Visual Studio Code (for syntax checking), and PyCharm (for detailed code analysis). Each is a great Python code editor. Also, I would like to give a special thanks to every GIMP plug-in author for sharing their inspirational work.

	- Charles Bartley
	June 1, 2025
